Skip to content

Recover saved generic CLI Turns without the host adapter - #9051

Merged
loopx-agent merged 1 commit into
mainfrom
codex/core-settlement-only-resume-20261119
Nov 21, 2026
Merged

loopx-agent merged 1 commit into
mainfrom
codex/core-settlement-only-resume-20261119

Conversation

@cocolord

@cocolord cocolord commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

User outcome

A generic CLI Turn can finish from its saved result after the original adapter is removed. Recovery uses the original Turn key and approved workspace. A pending independent check still needs its validator. A settled Turn returns its recorded result. If the typed recovery decision requires a new Host attempt, the CLI asks for the adapter before changing the original journal or acquiring a new start.

This uses the existing Turn command, typed recovery decision, lease proof and settlement owners. The paired small-kernel RFCs, standalone guide and command help describe the smaller recovery input.

Local validation

Tests used real CLI processes and isolated File/SQLite state with scripted local hosts. The scope is recovery of an existing task in the selected Core host path.

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent | Gemini | Google | self_reported

动机 / Motivation

适用对象与触发条件: 使用独立 loopx-core 安装包或 CLI 运行 generic-cli Turn 的调用方与运维方,在原 Turn 宿主进程已产出并持久化结果(待完成独立校验、待结算,或已结算需回读)但原外部宿主适配器脚本已移除或不再携带时,执行 --resume-turn-key(或解析后的 --resume-turn-instance-id)恢复回合。

修改前后场景对比: 修改前(基线 41ea75e):prepare_turn_host_arguments 与 _prepare_host_invocation 在 host == 'generic-cli' 时无条件强制要求 --host-adapter-command-json,导致即使原 Turn 已把宿主结果写入 journal 或已完成结算,只要调用方省去原适配器命令就会在参数解析/预备阶段直接失败退出,无法完成待校验结果的核验结算或已结算结果的只读回读;修改后(48d7951859):仅当恢复既有 Turn(--resume-turn-key 存在且未显式传入空 --host-command-json)时允许省略 --host-adapter-command-json 与 schema,并在读入并锁定原始 journal、由既有 assess_existing_turn_recovery 给出决策之后通过 _turn_transport_refusal 分流:已结算直接无副作用回读;待独立校验缺少 --validation-command-json 时拒止且保留原始 journal 字节;需要新一次宿主执行(reinvoke_host/needs_host)却缺少适配器时同样在任何日志修改或额度预约前拒止。

可观测收益: 在 SQLite 与 File 双后端的已构建安装版 loopx_core-2.4.0 wheel 实测中,删除原宿主适配器脚本后,--resume-turn-key 无适配器可继续完成 POSIX SIGKILL 后的独立校验与一次性提交结算、无适配器且无校验器可幂等回读已结算 Turn(all effects False);而对需要新 Host 尝试的失败回合或待校验缺少 --validation-command-json 的恢复请求,CLI 明确返回 unavailable 与所需参数提示,零副作用且 journal 字节与额度计数保持原样。

明确非目标与边界: 不放宽新建 generic-cli 回合(无 --resume-turn-key)或显式传入空字符串 --host-command-json 时的适配器要求,不绕过已有恢复状态机(assess_existing_turn_recovery / STOP_RESULT_KINDS),也不修改 codex-cli、dsh 或前端展示面。

改动思路 / Approach

如果不做这次改动,只要自主宿主脚本是临时生成或升级后路径变化,已经耗时完成外部模型产出的 generic-cli 回合在进程意外中断后就既无法继续跑独立校验、也无法仅凭 --resume-turn-key 安全回读已结算结果。与之相比,本 PR 并没有在 CLI 另造“只读回读/仅校验恢复”新命令,而是把原先过于靠前(尚未知晓 journal 处于什么恢复阶段就强制要求宿主命令)的传输检查拆分为两步:

turn run-once --host generic-cli [--resume-turn-key K]
  |-- 无 --resume-turn-key,或显式传了空 --host-command-json ""
  |     --> prepare_turn_host_arguments() 立即报错 ValueError(守住新建回合门槛)
  '-- 有 --resume-turn-key 且省略 --host-command-json
        --> prepare_turn_host_arguments() 返回 raw_argv=None
        --> _prepare_host_invocation(resume_existing_turn=True) 返回 (None, {})
        --> run_loopx_turn_once() 加文件锁读 journal,跑 assess_existing_turn_recovery()
              |-- action == "return_existing"(已结算)--> 无宿主/无校验器直接幂等回读
              '-- action == "continue" --> _turn_transport_refusal()(位于 journal 写与 cadence 预约之前):
                    |-- needs_host 或 reinvoke_host --> 返回 unavailable,提示补传 --host-adapter-command-json
                    |-- resume_from == "validation" 且非 STOP 终态且缺校验器 --> 返回 unavailable,提示补传 --validation-command-json
                    '-- 其余合法恢复(待校验且有校验器 / 待结算)--> 原 Turn 身份继续完成校验或结算

(Illustrative source-derived control-flow diagram against 48d7951859f95469178b46cfd421b2eff192ca67; tested behaviors verified via wheel & pytest below.)

架构分工与当前边界(architecture_assessment): 复用既有 Turn 恢复决策拥有者(assess_existing_turn_recovery、STOP_RESULT_KINDS 与单通道执行门控)而非新增旁路子命令或二次恢复状态机;参数传输层仅在 --resume-turn-key 下延后‘必须提供宿主 argv’的检查,由 run_loopx_turn_once 在加锁读取既有 journal 并得出恢复决策后经 _turn_transport_refusal 做精确拒止。 职责划分清楚:prepare_turn_host_arguments 与 _prepare_host_invocation 保持纯参数标准化,assess_existing_turn_recovery 保留唯一恢复决策权,_turn_transport_refusal 仅做动作前的传输充分性检查。本 PR 严格收窄在 CLI 参数传输放行与 run_loopx_turn_once 恢复前传输校验两层:仅覆盖 generic-cli 带 --resume-turn-key(含由 --resume-turn-instance-id 在 turn.py 解析赋值的路径)的恢复/只读回读入口,同步补充 README、CLI 帮助文案、双语 RFC 段落与安装版 Core wheel 回归测试。

具体改动 / Changes

本次精确提交 48d7951859f95469178b46cfd421b2eff192ca67(base 41ea75e89892ed88d0ae543e97e31aad0a181c47)共修改 8 个文件(+121 / -20):运行时源码 4 个文件(+53 / -14)、安装指南 1 个文件(+8 / -0)、双语 RFC 2 个文件(+11 / -0)与安装版 wheel 验收测试 1 个文件(+49 / -6)。

对照规范 docs/architecture/rfcs/monorepo-distribution-split-v0.md 在改动前基线修订 41ea75e89892ed88d0ae543e97e31aad0a181c47 的逐条核对如下(PR #9051 自身亦在 Governed lifecycle and external effects 节双语补充 1 段关于已持久化 generic-cli 结果无需原适配器即可恢复校验/结算与回读的说明,属于对既有恢复规则的精确补充而非放宽既有契约):

  • I2(implemented):唯一内核真值与单一恢复裁决者。run_loopx_turn_once 仍完全由 assess_existing_turn_recovery 决定当前 Turn 是否已结算、继续校验或需重跑宿主,_turn_transport_refusal 不引入第二套恢复状态机;由 tests/test_core_distribution.py 安装版 50 项测试验证。
  • I4(implemented):缺失必要执行依赖时显式报告不可用而非静默替代或篡改原记录。缺少必需适配器或校验器时返回 status == "unavailable" 及清晰参数提示;由 test_installed_core_resume_without_adapter_refuses_new_host_attempt 与 test_installed_core_recovers_confirmed_result_after_process_loss 验证。
  • I7(implemented):缺失执行前提必须在派发或副作用前失败。_turn_transport_refusal 在 stage_turn_decision_capture、complete_turn_host_source 与 admit_start 之前执行;新开回合省略 --host-adapter-command-json 仍在 prepare_turn_host_arguments 报错拒止。
  • I8(implemented):重放与恢复严格使用原持久化身份、已批准工作区与租约代次,并由独立校验器完成门禁后一次性结算。已在 SQLite 与 File 双后端的已安装 wheel 进程中断恢复及 --resume-turn-key 重放全量实测通过。

关键代码讲解

  1. prepare_turn_host_arguments(turn_host_request.py):将 generic-cli 的入口检查改为仅当提供了非空 host_command_json 时解析为 raw_argv;若省略(None)则只有在“未携带 --resume-turn-key”或“用户显式传了空字符串 ""”时才抛出 ValueError("generic-cli requires --host-adapter-command-json (alias --host-command-json)")。注意 turn.py#L152-L163 会先将 --resume-turn-instance-id 解析回填至 args.resume_turn_key,从而两条恢复标志自然共享此放行。
  2. _prepare_host_invocation 与 _turn_transport_refusal(executor.py):前者允许 resume_existing_turn=True 且 host_argv is None 返回 (None, {}) 以便读入 journal;后者在锁内评估恢复决策后、任何写盘或额度预约之前拦截三类非法输入:需要新一次宿主调用却缺适配器;待校验非 STOP_RESULT_KINDS 结果却缺 --validation-command-json;或携带适配器但 schema 不匹配。
  3. execute_turn_run_once(turn_run_once.py):向下游传入 resume_existing_turn=args.host == "generic-cli" and bool(getattr(args, "resume_turn_key", None)),严格把省略宿主命令的资格绑定到显式的 generic-cli 回合恢复路径。

对主干的风险 / Risks

  • 阻断级缺陷: 无(No blocking finding)。
  • 最坏回归场景与边界约束验证: 最大潜在风险在于“新建 generic-cli 回合被误放行导致运行时缺可执行命令”或“恢复一个需要重试宿主(host_result_contract 失败)的 Turn 时污染原 journal/额度预约”。针对上述两类反例已直接核验:prepare_turn_host_arguments 对无 --resume-turn-key 以及带 --resume-turn-key 但传 --host-command-json "" 均直接抛出 ValueError;test_installed_core_resume_without_adapter_refuses_new_host_attempt 实测证明失败宿主在无适配器下以 --retry-failed-turn 恢复会返回 status == "unavailable",所有 effects 均为 False,且磁盘 journal 字节指纹与 _spends(runtime) == 0 毫厘未改。
  • 范围适配、兼容与隔离评估: 所有新增参数与辅助函数均有现役生产调用方(turn_run_once.py 与 executor.py),无冗余分支或新增共享状态字段;未携带 --resume-turn-key 路径与非 generic-cli 主机行为保持严格基线等价;双语 RFC、包说明文档与 CLI 帮助文本同步一致。
  • 本地验证与残余风险: 本地实测已完整构建隔离 loopx_core-2.4.0 wheel 并跑通 tests/test_core_distribution.py + tests/control_plane/test_installed_core_context.py(50 passed in 131.45s),以及 5 套 turn/CLI 源码测试(507 passed in 312.89s),加上 ruff、mypy(17 文件)、check_rfc_bilingual.py、typecheck:control-plane、loopx check 与 canary premerge --tier quick(merge_gate_passed: true,0 告警)。残余说明:_prepare_host_invocation 对 host_argv=None 细粒度分支除了轮子端到端用例外亦经单元探针直接验证;按仓库策略未咨询远端 CI(wait_for_ci=false)。

我的整体评价 / Verdict

交付与影响判定(outcome_impact): long_horizon 与 user_experience 均判定为 improved —— 已完成外部宿主产出的中断/待校验/已结算 generic-cli Turn 在原宿主适配器已移除或路径迁移后仍可无阻塞完成校验、一次结算与幂等回读,减少长程流水线因适配器生命周期解耦造成的卡死。关于可视化界面评审(visual_review):inspected paths: loopx/cli_commands/turn_host_request.py, loopx/cli_commands/turn_registration.py, loopx/cli_commands/turn_run_once.py, loopx/control_plane/turn_driver/executor.py, packages/loopx-core/README.md — CLI/runtime 与文档变更,未涉及渲染界面。;unverified_scope: none。

语义、兼容性与代码体量结论: observable_semantics 判定为 intentional_change_validated(严格将“可省略适配器”限定于已存在 journal 恢复/回读的 generic-cli 路径并守住新回合与需重启宿主门槛);repository_reuse 为 reused;code_volume 为 necessary(兼容性保留全部现有命令行签名与恢复语义);change_proportionality 为 proportionate;default_off_isolation 为 isolated;authority_semantics 为 aligned;semantic_alignment 为 aligned(未引入新词表,沿用 STOP_RESULT_KINDS 与现有 Turn 恢复决策,双语 RFC Diff 检查与语义漂移门禁均通过)。

综上,在精确提交 48d7951859f95469178b46cfd421b2eff192ca67 上全部本地安装版与源码验证均全绿通过且无阻断问题,建议批准合入。

English Verdict: APPROVE

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · gpt-6.2-sol · OpenAI · runtime_reported · xhigh

动机 / Motivation

这项改动面向用独立 Core 或普通 CLI 运行 generic-cli Turn 的调用方。适配器可能由临时脚本提供,原结果持久化后调用方还要能完成独立校验或回读结果。在基线 41ea75e 上,原 Turn 已经结算时只要省略适配器参数,真实 CLI 仍会在解析参数后退出。调用方因此需要找回已经完成工作的宿主才能回读记录。

在 48d7951 上,原宿主脚本已移除时,同一 Turn 可继续独立校验并结算,结算后可仅凭原 Turn 身份回读。两种存储后端都经过实际安装包验证。恢复仍区分原结果可以继续处理、必须重启宿主和需要独立校验器三种情形。

实际生产 Host、跨平台交付、其他宿主实现和正式安装/发布分别验收。

改动思路 / Approach

是否需要宿主由已锁定的原 journal 和既有恢复决策决定,调用入口只传递原宿主参数是否存在。当前 PR 的边界是 generic-cli 已有 Turn 的命令行恢复,以及新宿主或独立校验器缺失时的前置拒绝。

让 CLI 直接放行所有缺适配器的调用改动更小,但会把缺执行前提的请求送到后续阶段。另设回读命令只能覆盖已经结算的那一端。这个提案通过同一命令覆盖回读、待校验恢复和待重试的区分,保持原 journal、lease、validation 和 settlement 的拥有者。今后的宿主分发重组仍可沿这条路径独立验证。

具体改动 / Changes

完整净改动为 8 个文件,+121/-20。CLI 的 prepare_turn_host_arguments 把有恢复键时的参数省略传到驱动。显式给出的空字符串或非 argv 数组仍由原解析边界处理。 execute_turn_run_once 仅在 generic-cli 有既有恢复键时设置 resume_existing_turn。命令帮助及 Core README 给出恢复时需保留的原身份和独立校验参数。

驱动的 _prepare_host_invocation 让缺出站传输的恢复走到相同的 journal 决策。_turn_transport_refusal 在准备新宿主尝试和预约前检查传输和验证器。已有结果的读回分支仍按旧协议返回原 receipt。配对 RFC 把该边界写入生命周期章节。安装包测试覆盖读取、进程退出后的恢复、租约变化、坏产物拒绝及重试缺适配器。两处关键实现分别见 入口解析 和 驱动拒绝逻辑。

规范基线见 monorepo-distribution-split-v0.md。I2 对应唯一 journal 与结算拥有者,I7 对应缺执行依赖在派发前失败,I8 对应原身份回读和一次性结算。独立构建了该基线和 PR 的 Core wheel,对相同类型的合成任务执行两套 File/SQLite 对照。旧版仅接受带适配器的回读,当前提交带和不带适配器两条回读都返回原 key、原结果和四项零 effect。换调用目录的已结算回读在两版都保持无副作用,非原 Agent 的恢复在两版都被拒绝。

对主干的风险 / Risks

无阻断发现。关键的失败边界是已经保存结果但仍缺验证器,或者实际上要启动又一次宿主执行。轮子实测显示两条恢复请求以带参数指引的 unavailable 返回,原 journal 字节和额度计数保持原样。对已续租或释放租约的反例,调用不写入状态,任务保持 open。缺适配器输入仅在原 journal 的相应阶段接受,原先需要适配器的新建请求仍使用同一输入校验。

安装版定向 16 项通过,源码恢复与 claim/preflight 定向 69 项通过。File/SQLite 的独立成对试验两侧各 2 项通过,覆盖原使用路径、错 Agent 和原 journal 与扣额数量。第一次 quick premerge 的 6 项直接检查通过,唯一执行失败是输出预算 smoke 超时;按同一基线分离执行该完整 smoke 已通过,随后未调高超时上限的完整 quick premerge 重新执行,6 项直接和 4 项所选检查全部通过。初次独立试验中“换目录必然拒绝”的断言在已结算回读上失败,后续用两版确认这是已有的只读行为。这里覆盖 macOS arm64 上的局部真实安装与源码路径。实际生产宿主失联、远端 CI 和未打包平台的结果留待各自验证。

我的整体评价 / Verdict

通过这个增量。最有价值的结果是宿主进程或脚本退出后,已经验收的成果仍可读回,待验成果可继续同一 Turn 的验证,不要求调用方再次调度宿主。当前改动在最合适的时间检查可用传输,并沿用原本的 journal、恢复和配对验证能力。额外的同账户 Gemini 批准已核对,当前结论基于这次独立安装包验证。

改动范围为 CLI、恢复驱动和配套文档及测试,适用范围没有渲染界面。未验证范围为真实生产宿主及非 macOS 安装组合。本结论针对当前源码与实际测试的安装产物,发布与合入资格另由原生门禁核对。

English verdict: APPROVE at 48d7951. Installed File/SQLite controls validate adapter-free recovery and terminal replay, including refusal before effects when a validator or new Host is required.

@loopx-agent
loopx-agent merged commit 16f4188 into main Nov 21, 2026
45 of 57 checks passed
@loopx-agent
loopx-agent deleted the codex/core-settlement-only-resume-20261119 branch November 21, 2026 13:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants